home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 011-020 / amok19 / dossupport / dossupport.doc < prev    next >
Text File  |  1993-11-04  |  6KB  |  178 lines

  1. ======================================================================
  2. Documentation for module "DosSupport" revision 1.3
  3. Author: Nicolas Benezan, Postwiesenstr. 2, 7000 Stuttgart 60, Germany
  4. ======================================================================
  5.  
  6. Copyright remarks
  7. ­­­­­­­­­­­­­­­­­
  8. (C) Copyright 1988 by Nicolas Benezan. All rights reserved.
  9. The whole package (source, documentation and code) is donated to
  10. public domain and may be copied and redistributed providing that...
  11.  
  12. * my name and this copyright remark and
  13. * the completeness of the package remain intact,
  14. * it's distributet for non-profit only.
  15.  
  16. Commercial use without my explicit, written permission is not
  17. allowed. Contact me to get it and, perhaps, to pay some fee.
  18.  
  19. Improvements and new ideas are welcome, as long as the changes are
  20. well documented inline and in the documentation files. I´would like
  21. to know, if you make major changes and repost it.
  22.  
  23.  
  24. Contents
  25. ­­­­­­­­
  26. * Package
  27. * Introduction
  28. * Data types
  29. * Procedures
  30. * Segments
  31. * Additional hints
  32. * Referenced literature
  33.  
  34.  
  35. Package
  36. ­­­­­­­
  37. The whole package "DosSupport" consists of following files:
  38.  
  39. * DosSupport.doc        This documentation file
  40. * DosSupport.dok        German documentation
  41. * DosSupport.def        Definition module
  42. * DosSupport.mod        Implementation module
  43. * DosSupport.sym        Symbol file
  44. * DosSupport.obj        Compiled object code
  45.  
  46.  
  47. Introduction
  48. ­­­­­­­­­­­­
  49. For some mysterious reason there are two competing Systems inside your
  50. Amiga: Exec (written in C) and AmigaDos (written in BCPL). For some
  51. even more mysterious reason, BCPL uses Pointers which are not simple
  52. Address easily accessible to the CPU but Adresses divided by 4.
  53. This discrepancy is very underdocumented and if you don't cope with
  54. it, it will bring you lots of hours of meditation...
  55. The module "DosSupport" suplies Procedures to convert the pointer-
  56. types into one another.
  57. The new version 1.1 contains some additional stuff necessary to deal
  58. with "Hunks" and "Segments". The AmigaDos load file format (Hunks)
  59. is described in [1]. You may also read the chapter "Segments" of
  60. this documentation.
  61.  
  62.  
  63. Data types
  64. ­­­­­­­­­­
  65. BCPL types
  66. ----------
  67. ADDRESS: simple memory address (byte address) as used by the 68000 CPU
  68.  
  69. BPTR (BCPL-pointer): an address divided by 4, also called
  70.         longword-address. All items referenced by such pointers must
  71.         begin at an address which is a multiple of 4.
  72.  
  73. C/Modula string: several ASCII-characters (ARRAY OF CHAR) followed by
  74.         an ASCII.nul as termination mark.
  75.  
  76. BSTR (BCPL string): BCPL-pointer to a byte which contains the number
  77.         of characters that follow this byte.
  78.         In other words:
  79.         There is an ARRAY [0..m] OF CHAR. Array[1]..Array[n] contain
  80.         the actual characters. Array[0] contains CHAR(n), it tells
  81.         us how many characters this string has. Finaly, there's
  82.         a BCPL-pointer which is equal to ADR(Array) DIV 4.
  83.         (it's terrible, isn't it).
  84.  
  85. Device list types
  86. -----------------
  87. The new TYPE "DeviceListPtr" was added to simplify the use of the
  88. Dos.DeviceList in Modula-2. Be careful and don't mix it up with the TYPE
  89. "DeviceListPtr" in module Dos (it's a BPTR).
  90.  
  91. The entry "startup" of a "Dos.DeviceList"-RECORD is not a LONGINT but a
  92. BCPL-pointer to a "StartupInfo"-RECORD, which itself contains a BPTR to a
  93. "DiskInfo"-RECORD. Both RECORDS contain important information about the
  94. disk device (see Mountlist).
  95.  
  96.  
  97. Procedures
  98. ­­­­­­­­­­
  99.  
  100. BPTRtoADR()
  101. -----------
  102. converts a BCPL-pointer into a Modula-ADDRESS
  103.  
  104. ADRtoBPTR()
  105. -----------
  106. does the reverse (be careful, the ADDRESS must be a multiple of 4)
  107.  
  108. BSTRtoStr()
  109. -----------
  110. copies a BSTR into a Modola-string (ARRAY OF CHAR) providing the final
  111. ASCII.nul
  112.  
  113. StrToBCPL()
  114. -----------
  115. converts a Modula-string into a BCPL-String by shifting the characters
  116. one position right and writing the string's length into the first
  117. byte. You get a real BSTR by the expression
  118. ADRtoBPTR(ADR(convertedString)).
  119.  
  120. GetDevList()
  121. ------------
  122. returns a (Modula-) pointer to the first entry of the Dos' DeviceList.
  123. In this list you will find all Volumes, Devices an assigned Directories
  124. currently available. Be careful, the entries are linked by BPTRs rather
  125. than Modula-pointers (DeviceList.next is of type BPTR).
  126. Don't forget to Forbid() while accessing the list.
  127.  
  128.  
  129. Segments
  130. ­­­­­­­­
  131. If an executable program is loaded into memory via Dos.LoadSeg() it is
  132. devided into segments, depending on the number of hunks it consists of,
  133. and scattered across memory. LoadSeg returns a BCPL-pointer (BPTR) to
  134. the first Segment of a linked list. It points to one longword BEFORE
  135. the beginning of the first code or data section. this longword contains
  136. a BPTR to the longword before the next segment and so on. Two longwords
  137. before the beginning of each segment there is a longword containing
  138. the size of that segment in bytes including the two additional longwords.
  139. In Modula it would be difficult to access the segments because of the
  140. negative offsets of the two longwords described above and the BPTRs.
  141. Fields of RECORDs can only have positive offsets in Modula-2. The
  142. Procedure GetSegmentAddr() simpifies the handling of BPTRs and ADDRESSes
  143. of segments.
  144.  
  145.   VAR     Seg:SegmentPtr;
  146.   ...
  147.   Seg:=GetSegmentAddr(LoadSeg(...));
  148.  
  149. can be used to get a pointer to the first loaded segment.
  150.  
  151.   Seg:=GetSegmentAddr(Seg^.nextSegment);
  152.  
  153. points to the next segment (or is NIL, if no further segment exists).
  154. To get the size of the data or code section of a segment, use
  155.  
  156.   Size:=Seg^.segmentSize-8; (* 8=2*SIZE(LONGWORD) *).
  157.  
  158.  
  159. Some Hints..
  160. ­­­­­­­­­­­­
  161. DosSupport exports DosBase which is normally very difficult to access
  162. in Modula. (Do not modify it!)
  163.  
  164. If you're working with a old compiler manual (version v3.1 or before)
  165. you might have a wrong listing of the Dos' definition module. All
  166. BPTRs and BSTRs are declared as ADDRESS in those manuals. Please watch
  167. out for an update (version 3.11 or better V3.2).
  168.  
  169.  
  170. Referenced literature
  171. ­­­­­­­­­­­­­­­­­­­­­
  172. [1] "AmigaDos Technical Reference Manual", CBM, Chapter 2.2
  173.  or "AmigaDos Manual", Bantam Books
  174.  
  175. [2] "Amiga Rom Kernel Reference Manual: Exec",
  176.     Appendix B: AmigaDos general information, CBM, Addison Wesley
  177.  
  178.